package za.org.jcicada.katcp;

/**
 * ISensor.java
 *
 * @author Simon Cross
 *
 * Created on October 14, 2008, 12:13
 */

/**
 * Represents a KAT device sensor.
 *
 * This interface comes equiped with enums
 * for sensor Type, Status and (sampling) Strategy
 */
public interface ISensor {

    /**
     * Sensor Types.
     */
    public enum Type {
        /** Integer sensor. */ INTEGER,
        /** Floating point sensor. */ FLOAT,
        /** Boolean sensor. */ BOOLEAN,
        /** Line replaceable unit sensor. */ LRU,
        /** Discrete sensor. */ DISCRETE;

        /**
         * Return the name of the type value.
         *
         * @return  The KATCP name for the sensor Type. 
         */
        public String katcpName() {
            return name().toLowerCase();
        }

        /**
         * Find a Type for the given KATCP name.
         *
         * @param name  KATCP sensor type name to lookup.
         * @return  KATCP sensor type corresponding to the name given.
         */
        public static Type fromKatcpName(String name) {
            Type type;
            try {
                type = Type.valueOf(Type.class, name.toUpperCase());
            }
            catch (IllegalArgumentException e) {
                throw new IllegalArgumentException(String.format("Unknown sensor type name '%s'", name));
            }
            return type;
        }
    }

    // Interface Methods

    /**
     * Return the name of the sensor.
     *
     * @return  The name of sensor.
     */
    String getName();

    /**
     * Return a description of the sensor.
     *
     * @return  A description of the sensor.
     */
    String getDescription();

    /**
     * Return the sensor units in a form suitable for display next to the
     * sensor value.
     *
     * @return  A string containing the units for this sensor.
     */
    String getUnits();

    /**
     * Return the sensor type.
     *
     * @return  The Type of this sensor.
     */
    Type getType();

    /**
     * Return the type parameters.
     *
     * @return  The parameters for this sensor as Strings.
     */
    String[] getParameters();

    /**
     * Format a sensor value of the same type as this ISensorType object.
     *
     * @param value  The value to format.
     * @return  KATCP string representation of the value as appropriate for
     *          this sensor type.
     */
    String formatValue(ISensorValue value);

    /**
     * Read the sensor and return an ISensorValue.
     *
     * @return  The current sensor value.
     */         
    ISensorValue read();

    /**
     * Set the sensor value.
     *
     * @param value  The new value for the sensor.
     */         
    void set(ISensorValue value);

    // TODO: Perhaps move these methods elsewhere once sampling is set up

    /**
     * Apply a change to the sensor sampling strategy.
     *
     * @param strategy  The new sampling strategy to use.
     * @see #getSampling
     */
    void setSampling(ISamplingStrategy strategy); 
    
    /**
     * Return the current sampling strategy.
     *
     * @return strategy  The current sampling strategy for this sensor.
     * @see #setSampling
     */
    ISamplingStrategy getSampling();

}
